<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Mesquite Build Instructions</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>

<body>
              <h2><font face="Trebuchet MS">Building a Mesquite Release with Ant and Eclipse</font></h2>
              
<p><font face="Trebuchet MS">This document discusses launching and editing <a href="http://ant.apache.org">ant</a> 
  build files from within <a href="http://www.eclipse.org">Eclipse</a>. An <a href="http://help.eclipse.org/help30/index.jsp?topic=/org.eclipse.platform.doc.user/concepts/concepts-antsupport.htm">overview</a> 
  of doing so can be found on the Eclipse website. </font></p>
  <!--
              <hr>
              <h3><font face="Trebuchet MS">Edit the server deployment information (optional, only if using the automated file upload)</font></h3>
              <p>The build script must be configured so it knows where to upload generated build files.  To
                 configure server connection settings, follow these steps:
                 <ol>
                     <li>In the root of Mesquite Project, there is a directory called <em>buildfiles</em>.
				 In this directory, there is a file called <em>serverinfo.properties.sample</em>.
				 Copy this file and paste it back into the <em>buildfiles</em> directory, but call it 
              	 <em>serverinfo.properties</em>.</li>
                     <li>
						Edit the newly created <em>serverinfo.properties</em>, replacing the lines:
                        <pre>
username=
password=
host=
                        </pre> with the username, password, and hostname where the generated build files
                        should be uploaded.
					</li>
                     <li>Edit the <em>build.xml</em> file and edit the following lines by replacing 
                     	the current path locations with their desired locations on the server:
                     <pre>
		&lt;!-- The directory where the binary distributions are stored --&gt;
		&lt;property name="bininstalldir" value="${hostprefix}/mesquite_install_folder/" /&gt;
		&lt;!-- The directory where the source distributions are stored --&gt;
		&lt;property name="srcinstalldir" value="${hostprefix}/mesquite_source_folder/" /&gt;
		&lt;!-- The path to Mesquite_Folder on the server (for documentation) --&gt;
		&lt;property name="mesquitefolderinstalldir" value="/Mesquite_Folder/" /&gt;                         
                     </pre>
					 Be careful not to replace or edit the <em>${hostprefix}</em> part, as this
                     is the server identification that ant needs to upload the files.
                     For example, if you want the Mesquite install packages to go to a directory
                     called <em>/home/user/mesquiteinstalls</em> you would have a line that looked like
                     this:
                     <pre>
		&lt;!-- The directory where the binary distributions are stored --&gt;
		&lt;property name="bininstalldir" value="${hostprefix}/home/user/mesquiteinstalls/" /&gt;                         
                     </pre>
                 </ol>
              </p>
             -->
             <h3>Targets Quick-Reference</h3>
             <p>To execute the following commands, one needs only check the <em>packagedistandsrc</em>
             	checkbox:
<ol>
             	<li><em>init, clean, compile, package source and dist</em></li>
             	<li><em>init, clean, compile, build windowsinstaller</em> (needs to be run on a windows machine)</li>
             	<li><em>init, clean, compile, package source and dist, build windowsinstaller</em> (needs to be run on a windows machine)</li>
</ol>
             </p>
             <p>To build the javadocs, check the <em>javadoc</em> checkbox.</p>
              <h3>Installing NSIS then checking out and building the Windows installer project (optional, only on Windows)</h3>
              <p>In order to build the Windows installation file, the 
                 <a href="http://nsis.sourceforge.net/Main_Page">Nullsoft Install System (NSIS)</a> must
                 be installed on the machine prior to launching ant.  <em>makensis.exe</em> must also
                 be located in a directory on the Windows PATH.  Instructions for downloading and installing
                 NSIS can be found on the <a href="http://nsis.sourceforge.net/Download">NSIS website</a>.</p>
              <p>Once NSIS is installed, you will want to check out the Windows installer project, which is
              	located here: http://svn.mesquiteproject.org:8080/trunk/mesquiteinstaller/  The build script
              	expects this to be in the same workspace as the "Mesquite Project" that is being built.</p>
              <p>After NSIS is installed and the Mesquite Installer project is checked out, the Mesquite Installer
              	can be built by running the <em>packagedist</em>  (or <em>packagedistandsrc</em>) target in the main Mesquite build file.  This will
              	create a file in the <em>dist</em> directory called MesquiteInstaller.exe</p>
			  <h3><font face="Trebuchet MS">Establishing an Ant Launch Configuration and Running the Script</font></h3>
              <p>In the root of Mesquite Project, there is a directory called <em>buildfiles</em> which
                contains a file called <em>build.xml</em>.  
				  This is the ant build script that specifies how the Mesquite
                release build will proceed. In order  to launch this script from
                within Eclipse, you need to create one or more Eclipse launch
                
				  configurations.  Each Eclipse launch configuration will run
                one or more ant targets.</p>
				<p>For example, you might want to test the build process without uploading the files while you're still developing, 
					and then later have the build script upload the files when you're confident they are ready for release.
					In this scenario I might have a testing launch configuration called <em>Mesquite package distribution</em> that 
					runs the <em>packagedistandsrc</em> target, and another called <em>Mesquite deploy files</em> that runs 
					the <em>deployfiles</em> target when I'm ready to go live.</p>
				<p>
				  To establish an Eclipse launch configuration for the build file, follow these steps:
				<ol>
				  <li>In the Package Explorer view, right-click the <em>build.xml</em> file.</li>
				  <li>From the file's pop-up menu, select <b>Run As &gt; Ant Build...</b>. The launch configuration
				  	dialog opens.</li>
                  <li id="step3">Name the launch configuration something easy to remember, for instance 
                      <em>Mesquite package distribution</em> or <em>Mesquite deploy files</em>.</li>
				  <li>Select the desired targets you wish to execute from the <b>Targets</b> tab.
				  	(<em>packagedistandsrc</em> creates the binary and source distributions; <em>packageddist</em> that
				  	does the same but only for the binary distribution.
				  	For information on the the other targets please see <a href="#targetreference">the
				  	reference</a> at the bottom of this page.)</li>
					  <!--
				  <li><h4>(Optional -- only necessary if calling the <em>deployfiles</em> target in this configuration.)</h4> Click the <b>Classpath</b> tab.  
					  Select <b>Additional Tasks &amp; Support</b> and click 
                  	  <b>Add JARs</b>.  Select a file called <em>jsch-0.1.28.jar</em> located under the <em>buildfiles</em>
                        folder at the root of Mesquite Project.</li>
                        -->
                  <li>Make sure to save your configuration by clicking the <b>Apply</b> button in the 
                  	bottom-right corner of the screen.</li>
				  <li>You may now launch the build script by clicking <b>Run</b>.</li>
				  <li>To launch this script in the future, follow these steps:
				  	<ol>
	                  <li>From the <b>Run</b> menu, select the <b>External Tools</b> menu, then select
	              the <b>External Tools</b> item in that menu to bring up the External Tools dialog.</li>
	                  <li>In the left-side panel, select the launch configuration you created earlier 
	                      (it should be located under the <b>Ant Build</b> menu item).</li>
	                  <li>Click <b>Run</b></li>						  
				    </ol>
				  </li>
				  <li>To create another launch configuration, follow these steps:
				  	<ol>
						<li>From the <b>Run</b> menu, select the <b>External Tools</b> menu, then select
	              		the <b>External Tools</b> item in that menu to bring up the External Tools dialog.</li>
						<li>Select <b>Ant build</b> in the left-panel then click the <b>New</b> button
							at the bottom of the screen.</li>
						<li>Go to <a href="#step3">Step 3</a> in the previous launch configuration instructions to complete your
							new launch configuration.</li>
				    </ol>
				  </li>
				</ol>
              </p>
			  <h3>Generated Files</h3>
              <p>There are number of files generated by the build script.  The generated files are located
              in a directory called <em>dist</em> that is one-level above that of Mesquite Project.
              A short explanation of
              each follows:
              <ul>
                  <li><em>mesquite.dmg</em> -- A .dmg installation file for Max OS X (only produced if the script is run on Mac OS X)</li>
                  <li><em>mesquite.tgz</em> -- A gzipped Mesquite binary suitable for linux or other unix distributions</li>                  
                  <li><em>MesquiteInstaller.exe</em> -- The Windows setup file (only produced if the script is run on Windows)</li>
                  <!--
                  <li><em>mesquite.sit</em> -- (DANNY'S NOTE -- this currently is commented out because I don't have stuff installed, easy to re-establish if desired, though) A binary installation file for Mac OS X.
                  -->
                  <li><em>mesquiteSource.tgz</em> -- A gzipped copy of Mesquite's source that is suitable for importing within Eclipse</li>
                  <li><em>mesquiteSource.zip</em> -- A zipped copy of Mesquite's source that is suitable for importing within Eclipse</li>                  
                  <!--
                  <li><em>mesquiteSource.sit</em> -- (DANNY'S NOTE -- same as above about the .sit) A StuffIt zipped copy of Mesquite's source that is suitable for importing within Eclipse</li>
                  -->
              </ul></p>
              <h3>Token substitution</h3>
              <p>During the build process, a number of documentation files are copied.  During this copying,
              certain tokens are replaced in order to make sure that the documentation matches the current
              Mesquite version number, release date, and copyright date.  These tokens are:
              <ul>
                  <li><em>@MESQUITE_RELEASE_VERSION@</em> -- replaced with the value of mesquite.version as defined in this 
                      line of the build file:
                  <pre>
		&lt;property name="mesquite.version" value="1.1" /&gt;                      
                  </pre></li>
                  <li><em>@MESQUITE_RELEASE_DATE@</em> -- replaced with the release date (the date the script is run) in the format <em>May 8, 2006</em> (MMMM dd yyy)</li>
                  <li><em>@MESQUITE_RELEASE_YEAR@</em> -- replaced with the release year (of the date the script is run) in the format <em>2006</em> (yyyy)</li>
              </ul>
              In addition, any html files will have
              the following token substitutions in order to make local 
              links into or out of the Mesquite docs directory work:
              <ul>
                  <li>&lt;protectedURL&gt; -- replaced with &lt;</li>
                  <li>&lt;/protectedURL&gt; -- replaced with &gt;</li>
              </ul>
              </p>
              <h3 id="targetreference">Build target reference</h3>
              <p>Ant has its executable blocks set up in pieces called targets.  The following are the targets
                  in the Mesquite build file:
<ul>
    <li><em>init</em> -- The initialization point for the build file.  It establishes build variables like directory locations, etc.</li>
    <li><em>clean</em> -- Gets rid of any build-script related artifacts (i.e. class files, zip files, .dmg etc.)</li>
    <li><em>compile</em> -- Invokes javac on all the source files.</li>
    <li><em>packagedist</em> -- Packages the binary distribution files</li>
    <li><em>callwindowsinstaller</em> -- Calls the Windows installer build script.  This only executes on Windows.</li>
    <li><em>packagesrc</em> -- Builds a source distribution directory and includes a .classpath which Eclipse will read.
    <li><em>packagedistandsrc</em> -- Calls <em>packagedist</em> and <em>packagesrc</em>.  This is good for testing purposes.</li>						 
</ul>
              </p>
</body>
</html>

